home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / os2 / srefv12i.zip / counter.doc < prev    next >
Text File  |  1997-04-15  |  13KB  |  252 lines
  1. 15 Apr 1997:  Description of the SRE-Filter COUNTER.RXX add-on
  2.  
  3. A) Introduction ------------------
  4.  
  5. COUNTER.RXX is a flexible "hits" counter generator and request-information
  6. recorder. It can be invoked in a number of different manners:
  7.  
  8.  1) As a server side include (instead of <!-- REPLACE HITS -->):
  9.         COUNTER.RXX can generate a textual counter when "called"
  10.         as a server side  include.
  11.  2) As an in-line image (instead of the XCOUNT cgi-bin program):
  12.         COUNTER.RXX can generate a simple "odometer" style counter graphic.
  13.  3) In conjunction with SENDFILE, as a means of keeping track of
  14.     requests.
  15.  
  16.  The principal advantages of COUNTER.RXX are:
  17.    i) In text mode, it has several display options, including
  18.       inclusion of commas and a "st", "nd", etc. suffix
  19.   ii) Document unique  ".CNT" file are used to store results
  20.       (rather then the COUNTER_FILE, or the  ACCESS.CNT file used by
  21.       the XCOUNT and JCOUNT cgi-bin scripts).
  22.  iii) Request specific information (such as IP address, time of request,
  23.       and referer) can be stored.
  24.  iv)  Suppression of hits from "owners" and from "recent requesters"
  25.       can be invoked.
  26.  
  27. Acknowlegments: this is adapted from "The SSI Hit Counter" of William Herrin
  28.                 (http://www.why.com/herrin).
  29.  
  30.  
  31. B) How to install & use COUNTER.RXX  --------------
  32.  
  33.   1) Copy COUNTER.RXX to your GoServe working directory
  34.  
  35.   2) Create a (set of) .CNT files -- one for each "document" you wish
  36.      to "count requests for" (though it is permissible to have several
  37.      documents "share" a single .CNT file).
  38.  
  39.      NOTES:
  40.        *  In general, you should create these .CNT files beforehand --
  41.           COUNTER.RXX may FAIL if the indicated .CNT file does not exist
  42.           (for details, see the description of CREATE_FILE below)
  43.        *  When you create it, you should leave the .CNT files empty.
  44.  
  45.   3) As mentioned above, there are three ways you can invoke COUNTER.RXX
  46.  
  47.     a) As a "server side include" (a text counter is written)
  48.        Place  keyphrases into  your  HTML documents. For example:
  49.        These keyphrases should have the form:
  50.           <!-- INTERPRET FILE COUNTER.RXX  option_list , noaugment-->
  51.        where:
  52.             * option_list: a space delimited list of formatting instructions
  53.             * noaugment: if 1, do not augment the count (the current value  is
  54.                      used).
  55.  
  56.      b) As an in-line image (a simple black on white "odometer").
  57.         Place "in-line images" elements in your HTML documents. For example:
  58.               <IMG SRC="/COUNTER.RXX?option_list"> 
  59.         elements in your HTML documents, where:
  60.             * option_list is a & delimited list of formatting instructions
  61.                        (see below for details)
  62.             * option_list must include a GRAPHICS=value option in the option_list 
  63.                (along with the FILE=filename option)
  64.  
  65.     c) In conjunction with the SENDFILE facility.
  66.        Place "link" in your HTML documents. For example:
  67.           <a href="/SENDFILE?filename&counter=option_list">Send file </a>
  68.        links in your HTML documents. 
  69.         *  option_list is a  +  list of formatting instructions
  70.                        (see below for details)
  71.  
  72.   4) You may also want to change a few variables in COUNTER.RXX:
  73.  
  74.       a)  Counter_dir : If set to 0  (the default), the '.CNT' files
  75.            are expected to be  in the "requesting documents" own directory.
  76.            Otherwise, counter_dir should contain a fully qualified
  77.            directory name.
  78.  
  79.       b)  Write_users : If write_users=1, then along with the "number" of
  80.            hits, client specific information is recorded. See f) below for
  81.            details.
  82.            Notes:
  83.                 * if you use the write_users option, privacy concerns lead
  84.                   us to strongly recommend using a web-inaccessible
  85.                   counter_dir (i.e.; by setting COUNTER_DIR='\GOSERVE')
  86.                 * you may want to reset these .CNT files every so often
  87.                   (since large files will impact response time).
  88.                 * only the count is written to the "requesting document".
  89.                   The "user information" is written for the sake of
  90.                   the server administrator(s).
  91.  
  92.        c)   Suppress_recent: If non zero, and if Write_users=1, then
  93.             the user list is checked against the client's ip address.
  94.             If:
  95.                 i) if a matching entry (by ip address) exists
  96.                ii) it is less then suppress_recent minutes old,
  97.             Then:
  98.                 i) the counter is NOT incremented
  99.                ii) the current value is used in the server-side include
  100.  
  101.        d)   Suppress_owners: If equal to one, then if the request is
  102.             from an owner (as listed in the OWNERS variable), the counter
  103.             will not be incremented.
  104.  
  105.        e)   Create_file: If equal to one, will create a .CNT file
  106.             if none already exists.  Otherwise, if no .CNT file
  107.             exists, COUNTER will return nothing.
  108.  
  109.        f)    There are two output formats: Common-log format, and customized.
  110.           a)  To select "common-log" format, set common_log_format=1.  When
  111.              enabled, entries of the form:
  112. 151.121.65.143, 729109.895139, someone.clients.org - USERNAME [27/Mar/1997:21:29:58 -0500] "GET /status.htm HTTP/1.0" - 0
  113.             will be written (note that the status code is always set to -, and 
  114.             the size will be non-zero only if COUNTER.RXX is invoked via 
  115.             SENDFILE).
  116.  
  117.           b) For customized fornat, you enable (by setting =1) one, several, 
  118.              or all of the following "output field" variables:
  119.               save_ipname:    Write the "dotted" IP Name (if none available,
  120.                               save IP address)
  121.               save_username:  Write the SRE-Filter "logon" name (if available)
  122.               save_time:      Write the time, in 13:01:33 format
  123.               save_date:      Write the date, in 5 Feb 1996 format
  124.               save_docname:   Write the "request selector"
  125.               save_bytes:     Write the number of bytes written, and 
  126.                                       the size of the file.
  127.                                If a premature disconnection occurs, the number 
  128.                                of bytes written will be less then the size of 
  129.                                the file.
  130.               save_referer:   Write the "referer (if available)
  131.               save_browser:   Write the "user-agent"
  132.  
  133.           Note: in both cases, the client's ip address and the "julian" date/time are
  134.                 always written (given write_users=1)
  135.  
  136. C) Description of COUNTER.RXX "option list" options ---------
  137.  
  138.   The simplest option list is no option list.  If there is no option
  139.   list, a .CNT file (with the same name as the requested document) will
  140.   be used.
  141.   Notes:
  142.         * If you are using a counter_dir (say, counter_dir='d:\goserve'),
  143.           and you have files with the same name in several directories, they
  144.           will end up augmenting the same counter.
  145.         * For the "odomoter" (IMG SRC="/COUNTER.RXX.."> variant, you
  146.           MUST include the GRAPHICS option in the option list.
  147.  
  148.  Otherwise, the options are:
  149.   file="filename" : The name of the .CNT file (relative to
  150.                     the counter_dir, or relative to the the document's
  151.                     own directory if counter_dir=0).
  152.        silent=""  : If a silent is present, the .CNT file will be
  153.                     updated, but nothing will be displayed.
  154.     nocommas=""   : If present, every 3rd digit commmas are NOT written
  155.                     This is implied if width>0. If not specified,
  156.                     commas WILL be included.
  157.     width=ndigits : minimum width of counter (padded with 0's if need be).
  158.                     Default is 0 -- which means "don't try to pad".
  159.     min=min_value : minimum value to count from (the default is 0)
  160.     max=max_value : maximum value to count to (the default is 2147000000)
  161.     rollover=""   : if present, will reset counter to min when max is hit.
  162.                     Default is to not rollover.
  163.     increment=inc : add inc at each hit (typically, inc=1). 
  164.                      If increment=0, then the counter is NOT augmented, and
  165.                      a user-entry is NOT added.
  166.     ith=""        : if present, append a th,rd,st, or nd "suffix"
  167.                     to the number (1st, 2nd, 3rd, 4th, etc).
  168.                     Default is do NOT add this suffix.
  169.     sel=selector  :  If write_users is enabled, the value of SEL will be  
  170.                      written to the "selector" field (in the .CNT file).
  171.                      If SEL is not specified, the selector of that "invoked"
  172.                      COUNTER.RXX will be used.  
  173.                       Note: If you are using the GRAPHIC option,
  174.                              you should also use the SEL option.
  175.      graphic=arg   : If arg=YES, then a white on black background
  176.                      odometer graphic will be created. If arg=NORMAL,
  177.                      then a black on white background odometer will
  178.                      be created.  Note that if either a graphic=YES
  179.                      or graphic=NORMAL argument is included,
  180.                      nocommas is set to 1, and ith is set to 0.
  181.                      THIS ARGUMENT IS REQUIRED IF YOU ARE INVOKING COUNTER.RXX
  182.                      AS AN INLIME IMAGE.
  183.                      Note: it is strongly recommended that you include a SEL option when
  184.                            you use the GRAPHIC option.
  185.   duration=#days :  If duration>0, then the number of hits in the last "#days" will be displayed.
  186.                       For example, duration=1 means that the "number of hits today" is displayed.
  187.                       Similarly, duration=7 means "the number of hits in the last 7 days"
  188.                       will be displayed.
  189.                       Notes:
  190.                          *  For this to work, you MUST set  write_users=1. 
  191.                             If write_users<>1, then a value of 000 is displayed.
  192.                          *  The actual number of hits is displayed (minval,  rollover,
  193.                             etc. are ignored).
  194.                          *  If duration=0, it is ignored (i.e.; it's the same as not including
  195.                             a duration option).
  196.                          *  Hint: to report the total # of hits, and the hits in the last n days,
  197.                                   use  two calls, with the second containing an increment=0
  198.                                   option.
  199.                          *  Example:
  200.                              If duration = 7, and today is monday, then the number of
  201.                              hits since last Tuesday (inclusive) is displayed.
  202.  
  203.  
  204. D) Miscellaneous topics -----------
  205.  
  206.  
  207.  * Using COUNTER.RXX with SENDFILE ------------
  208.  
  209.    To augment these .CNT files via the SENDFILE facility, simply
  210.    include, as part of the args (in SENDFILE?filename&args)
  211.    a &COUNTER=file=cntfile.  Since SENDFILE just uses COUNTER.RXX
  212.    to augment the .CNT file, there is no point in specifying
  213.    additional options (however, you may wish to tinker with the SAVE_xxxx
  214.    variables in COUNTER.RXX).
  215.  
  216.    Example:  sendfile?srefiltr/ver12/srefv12i.zip&counter=file=sref12
  217.  
  218.    Note: SENDFILE will record all attempts in the .CNT file. However,
  219.          if an attempt failed (due to a prematurely closed connection),
  220.          SENDFILE will write a "failed" record that notes how
  221.          many bytes were sent.
  222.  
  223.  * Example of use as an in-line image
  224.        <IMG src="/counter.rxx?file=test1&width=5&graphic=YES">
  225.        <IMG src="/counter.rxx?file=test2&increment=0&graphic=NORMAL">
  226.  
  227.     Note the use of & as an argument seperator!
  228.  
  229.  
  230.  * Examples of use as a server side include:
  231.    <!-- INTERPRET FILE COUNTER.RXX file=foobar -->
  232.    <!-- INTERPRET FILE COUNTER.RXX file=foobar2 silent="" -->
  233.    <!-- INTERPRET FILE COUNTER.RXX file=foobar3 min=10 max=20 inc=2 width=5
  234.                                   rollover="" ith="" -->
  235.    <!-- INTERPRET FILE COUNTER.RXX file=foobar2 nocommas="" , 1  -->
  236.    <!-- INTERPRET FILE COUNTER.RXX file=foobar  duration=10 -->
  237.  
  238.  
  239.    Note that when called as a server side include, you don't need to
  240.    enclose the values in double quotes (").  Also note that space is used as an
  241.    argument seperator.
  242.  
  243.  
  244.  * In .CNT files: blank lines, and lines starting with a semi-colon,
  245.    are ignored (they are treated as comments)
  246.  * Suppress_recent is ignored if write_users does not equal 1
  247.  * Hint: if you want some counters to retain "individual information",
  248.          and some not to, you can create 2 versions of COUNTER.RXX
  249.          (say, CNT1.RXX and CNT2.RXX); and call the appropriate one:
  250.          say; use INTERPRET FILE CNT1.RXX or INTERPRET FILE CNT2.RXX.
  251.  
  252.